% -----------
% Copyright 2013-2014, Andrew Lindesay
% Distributed under the terms of the MIT License.
% -----------

\section{Build and Release}
\label{buildandrelease}

This section covers how to build the application server and how to produce release builds of it.

\subsection{Building}

The build process uses the \href{http://maven.apache.org}{Apache Maven} build tool.  This is discussed in the prerequisites at \ref{prerequisites}.

From source code, you can obtain a clean build by issuing the following command from the UNIX shell;

\framebox{\tt mvn clean \&\& mvn package}

Given the state of the source code, this will produce corresponding build artifacts.  Note that this may take some time for the first build because the process will need to download various dependencies from the internet.

\subsubsection{Linux}

Building on a linux host will also cause the build system to produce an RPM file.  The RPM tooling is required on the build host to make this possible.  More detail about this can be found at \ref{prerequisites-buildingonlinux}.

\subsection{Automated Testing}

The build system has a number of automated tests.  To skip automated testing, use the {\tt -DskipTests} flag on the ``mvn" command.

\subsubsection{Integration Testing}
\label{integrationtesting}

Some of the automated tests are ``integration tests''.  The integration tests can be run with the following maven command;

\framebox{\tt mvn clean \&\& mvn verify}

The integration tests {\bf require} the presence of a specifically configured Postgres database in order to execute.  The database for the execution of integration tests should be available at localhost:5432 where the build is occurring.  The database should be setup as follows;

\begin{tabular}{ | l | l | }
  \hline
  Database name & {\tt haikudepotserver\_integrationtest} \\
  Database owner & {\tt haikudepotserver\_integrationtest} \\
  User & {\tt haikudepotserver\_integrationtest} \\
  User password & {\tt haikudepotserver\_integrationtest} \\
  \hline
\end{tabular}

The configuration for accessing this database is located in the file {\tt local.properties} within the test resources of the {\tt haikudepotserver-webapp} module, but it should not be necessary to edit this file.  As part of the integration testing process, the database schema objects in the integration test database will be dropped and will be re-assembled from scratch before each test is undertaken.  This ensures a clean test each time.

\subsection{Release}

A maven project has a ``version'' which is either a final version such as ``2.3.1'' or is a {\it snapshot} version such as ``2.3.2-SNAPSHOT''.  The snapshot version is the work-in-progress for the next release.  Once the snapshot is ready, a release is made wherein that source-code is fixed to the version number without the trailing ``-SNAPSHOT'' and then the snapshot version is incremented.  The release yields a tag in the source code management system (git) in order to be able to reproduce the source-code for that release against a release version.  The tag will have a form such as ``haikudepotserver-2.3.2''.

\subsubsection{Undertaking a Release}

The system {\it was} using the maven release plugin, but some issues arose with the maven release plugin and git.  For this reason, a bespoke scripted release process has been developed.  The script does none of the checks and tests that the maven release plugin does.

In the following example, the following assumed (ficticious) version numbers are used for demonstration purposes;

\begin{tabular}{ | l | l | }
\hline
Version & Purpose \\
\hline
{\tt 1.2.3-SNAPSHOT} & The version {\bf prior} to release \\
{\tt 1.2.3} & The version of the release  \\
{\tt 1.2.4-SNAPSHOT} & The version {\bf after} the release \\
\hline
\end{tabular}

The script does perform the following steps;

\begin{enumerate}
\item Check the current version is of the form 1.2.3-SNAPSHOT
\item Check all modules have the same version
\item Update all modules to the version 1.2.3
\item Git commit
\item Git tag
\item Update all modules to the version 1.2.4-SNAPSHOT
\item Git commit
\end{enumerate}

Prior to a release;

\begin{enumerate}
\item All changes should be committed.
\item A {\it verify} goal is run to ensure that automated testing passes.
\item A {\it clean} goal is run to clean out any build files
\end{enumerate}

The following series of commands would orchestrate the release process;

\begin{verbatim}
python support/hdsrelease.py
git push
git push --tags
\end{verbatim}

\subsubsection{Obtaining Source for a Release}

In order to obtain source code state for a specific release, first {\tt git pull} any pending changes from the remote repository and then checkout the source at the particular tag;

\framebox{\tt git checkout tags/haikudepotserver-2.3.2}

From there it will be possible to create a build product for that particular release by initiating the build process.